Автентифікація в TypeScript: Патерни типізованої безпеки JWT для глобальних застосунків

У сучасному взаємопов'язаному світі створення безпечних та надійних глобальних застосунків має першочергове значення. Автентифікація, процес перевірки особистості користувача, відіграє критичну роль у захисті конфіденційних даних та забезпеченні авторизованого доступу. JSON Web Tokens (JWT) стали популярним вибором для реалізації автентифікації завдяки своїй простоті та портативності. У поєднанні з потужною системою типів TypeScript автентифікація JWT може стати ще більш надійною та простою в обслуговуванні, особливо для великомасштабних міжнародних проєктів.

Чому варто використовувати TypeScript для JWT-автентифікації?

TypeScript надає кілька переваг при створенні систем автентифікації:

• Безпека типів: Статична типізація TypeScript допомагає виявляти помилки на ранніх етапах розробки, знижуючи ризик несподіванок під час виконання. Це надзвичайно важливо для компонентів, що стосуються безпеки, таких як автентифікація.
• Покращена підтримка коду: Типи забезпечують чіткі контракти та документацію, що полегшує розуміння, модифікацію та рефакторинг коду, особливо в складних глобальних застосунках, де може бути залучено кілька розробників.
• Розширене автодоповнення коду та інструменти: IDE, що підтримують TypeScript, пропонують краще автодоповнення коду, навігацію та інструменти для рефакторингу, підвищуючи продуктивність розробників.
• Зменшення шаблонного коду: Такі функції, як інтерфейси та дженерики, можуть допомогти зменшити кількість шаблонного коду та покращити його повторне використання.

Розуміння JWT

JWT — це компактний та безпечний для URL спосіб представлення тверджень (claims) для передачі між двома сторонами. Він складається з трьох частин:

1. Заголовок: Вказує алгоритм та тип токена.
2. Корисне навантаження (Payload): Містить твердження, такі як ID користувача, ролі та час закінчення терміну дії.
3. Підпис: Забезпечує цілісність токена за допомогою секретного ключа.

JWT зазвичай використовуються для автентифікації, оскільки їх легко перевірити на стороні сервера без необхідності запиту до бази даних для кожного запиту. Однак зберігати конфіденційну інформацію безпосередньо в корисному навантаженні JWT, як правило, не рекомендується.

Реалізація типізованої JWT-автентифікації в TypeScript

Давайте розглянемо деякі патерни для створення типізованих систем JWT-автентифікації в TypeScript.

1. Визначення типів корисного навантаження за допомогою інтерфейсів

Почніть з визначення інтерфейсу, що представляє структуру вашого корисного навантаження JWT. Це забезпечить безпеку типів при доступі до тверджень у токені.

interface JwtPayload {
  userId: string;
  email: string;
  roles: string[];
  iat: number; // Issued At (timestamp)
  exp: number; // Expiration Time (timestamp)
}

Цей інтерфейс визначає очікувану структуру корисного навантаження JWT. Ми включили стандартні твердження JWT, такі як `iat` (час видачі) та `exp` (час закінчення терміну дії), які є критично важливими для керування валідністю токена. Ви можете додати будь-які інші твердження, що стосуються вашого застосунку, наприклад, ролі чи дозволи користувача. Рекомендується обмежувати твердження лише необхідною інформацією, щоб мінімізувати розмір токена та підвищити безпеку.

Приклад: Керування ролями користувачів у глобальній e-commerce платформі

Розглянемо платформу електронної комерції, що обслуговує клієнтів по всьому світу. Різні користувачі мають різні ролі:

• Адміністратор: Повний доступ до керування продуктами, користувачами та замовленнями.
• Продавець: Може додавати та керувати власними продуктами.
• Клієнт: Може переглядати та купувати продукти.

Масив `roles` в `JwtPayload` можна використовувати для представлення цих ролей. Ви можете розширити властивість `roles` до більш складної структури, що детально описує права доступу користувача. Наприклад, це може бути список країн, в яких користувач може працювати як продавець, або масив магазинів, до яких користувач має адміністративний доступ.

2. Створення типізованого сервісу JWT

Створіть сервіс, який відповідає за створення та перевірку JWT. Цей сервіс повинен використовувати інтерфейс `JwtPayload` для забезпечення безпеки типів.

import jwt from 'jsonwebtoken';

const JWT_SECRET = process.env.JWT_SECRET || 'your-secret-key'; // Зберігайте безпечно!

class JwtService {
  static sign(payload: Omit, expiresIn: string = '1h'): string {
    const now = Math.floor(Date.now() / 1000);
    const payloadWithTimestamps: JwtPayload = {
        ...payload,
        iat: now,
        exp: now + parseInt(expiresIn) * 60 * 60,
    };
    return jwt.sign(payloadWithTimestamps, JWT_SECRET);
  }

  static verify(token: string): JwtPayload | null {
    try {
      const decoded = jwt.verify(token, JWT_SECRET) as JwtPayload;
      return decoded;
    } catch (error) {
      console.error('JWT verification error:', error);
      return null;
    }
  }
}

Цей сервіс надає два методи:

• `sign()`: Створює JWT з корисного навантаження. Він приймає `Omit`, щоб гарантувати, що `iat` та `exp` генеруються автоматично. Важливо зберігати `JWT_SECRET` безпечно, в ідеалі використовуючи змінні середовища та рішення для керування секретами.
• `verify()`: Перевіряє JWT і повертає декодоване корисне навантаження, якщо воно валідне, або `null`, якщо невадільне. Ми використовуємо приведення типу `as JwtPayload` після перевірки, що є безпечним, оскільки метод `jwt.verify` або викидає помилку (яка перехоплюється в блоці `catch`), або повертає об'єкт, що відповідає визначеній нами структурі корисного навантаження.

Важливі аспекти безпеки:

• Керування секретним ключем: Ніколи не жорстко кодуйте ваш секретний ключ JWT у коді. Використовуйте змінні середовища або спеціалізований сервіс для керування секретами. Регулярно змінюйте ключі.
• Вибір алгоритму: Обирайте сильний алгоритм підпису, такий як HS256 або RS256. Уникайте слабких алгоритмів, таких як `none`.
• Термін дії токена: Встановлюйте відповідний час закінчення терміну дії для ваших JWT, щоб обмежити наслідки компрометації токенів.
• Зберігання токена: Зберігайте JWT безпечно на стороні клієнта. Варіанти включають HTTP-only cookie або локальне сховище з відповідними заходами проти XSS-атак.

3. Захист кінцевих точок API за допомогою middleware

Створіть middleware для захисту ваших кінцевих точок API шляхом перевірки JWT у заголовку `Authorization`.

import { Request, Response, NextFunction } from 'express';

interface RequestWithUser extends Request {
  user?: JwtPayload;
}

function authenticate(req: RequestWithUser, res: Response, next: NextFunction) {
  const authHeader = req.headers.authorization;

  if (!authHeader) {
    return res.status(401).json({ message: 'Unauthorized' });
  }

  const token = authHeader.split(' ')[1]; // Припускаючи, що це Bearer token
  const decoded = JwtService.verify(token);

  if (!decoded) {
    return res.status(401).json({ message: 'Invalid token' });
  }

  req.user = decoded;
  next();
}

export default authenticate;

Це middleware витягує JWT із заголовка `Authorization`, перевіряє його за допомогою `JwtService` і прикріплює декодоване корисне навантаження до об'єкта `req.user`. Ми також визначаємо інтерфейс `RequestWithUser`, щоб розширити стандартний інтерфейс `Request` з Express.js, додаючи властивість `user` типу `JwtPayload | undefined`. Це забезпечує безпеку типів при доступі до інформації про користувача в захищених маршрутах.

Приклад: Обробка часових поясів у глобальному застосунку

Уявіть, що ваш застосунок дозволяє користувачам з різних часових поясів планувати події. Ви можете зберігати бажаний часовий пояс користувача в корисному навантаженні JWT для коректного відображення часу подій. Ви можете додати твердження `timeZone` до інтерфейсу `JwtPayload`:

interface JwtPayload {
  userId: string;
  email: string;
  roles: string[];
  timeZone: string; // напр., 'America/Los_Angeles', 'Asia/Tokyo'
  iat: number;
  exp: number;
}

Потім у вашому middleware або обробниках маршрутів ви можете отримати доступ до `req.user.timeZone` для форматування дат і часу відповідно до уподобань користувача.

4. Використання автентифікованого користувача в обробниках маршрутів

У ваших захищених обробниках маршрутів ви тепер можете отримувати доступ до інформації про автентифікованого користувача через об'єкт `req.user` з повною безпекою типів.

import express, { Request, Response } from 'express';
import authenticate from './middleware/authenticate';

const app = express();

app.get('/profile', authenticate, (req: Request, res: Response) => {
  const user = (req as any).user; // або використовуйте RequestWithUser
  res.json({ message: `Привіт, ${user.email}!`, userId: user.userId });
});

Цей приклад демонструє, як отримати доступ до електронної пошти та ID автентифікованого користувача з об'єкта `req.user`. Оскільки ми визначили інтерфейс `JwtPayload`, TypeScript знає очікувану структуру об'єкта `user` і може забезпечити перевірку типів та автодоповнення коду.

5. Реалізація контролю доступу на основі ролей (RBAC)

Для більш детального контролю доступу ви можете реалізувати RBAC на основі ролей, що зберігаються в корисному навантаженні JWT.

function authorize(roles: string[]) {
  return (req: RequestWithUser, res: Response, next: NextFunction) => {
    const user = req.user;

    if (!user || !user.roles.some(role => roles.includes(role))) {
      return res.status(403).json({ message: 'Forbidden' });
    }

    next();
  };
}

Це `authorize` middleware перевіряє, чи містять ролі користувача будь-яку з необхідних ролей. Якщо ні, воно повертає помилку 403 Forbidden.

app.get('/admin', authenticate, authorize(['admin']), (req: Request, res: Response) => {
  res.json({ message: 'Ласкаво просимо, Адміністраторе!' });
});

Цей приклад захищає маршрут `/admin`, вимагаючи, щоб користувач мав роль `admin`.

Приклад: Обробка різних валют у глобальному застосунку

Якщо ваш застосунок обробляє фінансові транзакції, вам може знадобитися підтримка кількох валют. Ви можете зберігати бажану валюту користувача в корисному навантаженні JWT:

interface JwtPayload {
  userId: string;
  email: string;
  roles: string[];
  currency: string; // напр., 'USD', 'EUR', 'JPY'
  iat: number;
  exp: number;
}

Потім у вашій бізнес-логіці на бекенді ви можете використовувати `req.user.currency` для форматування цін та виконання конвертації валют за потреби.

6. Токени оновлення (Refresh Tokens)

JWT за своєю природою є короткоживучими. Щоб уникнути необхідності частого входу користувачів, реалізуйте токени оновлення. Токен оновлення — це довгоживучий токен, який можна використовувати для отримання нового токена доступу (JWT) без повторного введення облікових даних користувачем. Зберігайте токени оновлення безпечно в базі даних та пов'язуйте їх з користувачем. Коли термін дії токена доступу користувача закінчується, він може використати токен оновлення, щоб запросити новий. Цей процес необхідно ретельно реалізувати, щоб уникнути вразливостей безпеки.

Просунуті техніки безпеки типів

1. Дискриміновані об'єднання для детального контролю

Іноді вам можуть знадобитися різні корисні навантаження JWT залежно від ролі користувача або типу запиту. Дискриміновані об'єднання (discriminated unions) можуть допомогти вам досягти цього з безпекою типів.

interface AdminJwtPayload {
  type: 'admin';
  userId: string;
  email: string;
  roles: string[];
  iat: number;
  exp: number;
}

interface UserJwtPayload {
  type: 'user';
  userId: string;
  email: string;
  iat: number;
  exp: number;
}

type JwtPayload = AdminJwtPayload | UserJwtPayload;

function processToken(payload: JwtPayload) {
  if (payload.type === 'admin') {
    console.log('Admin email:', payload.email); // Доступ до email безпечний
  } else {
    // payload.email тут недоступний, оскільки тип 'user'
    console.log('User ID:', payload.userId);
  }
}

Цей приклад визначає два різні типи корисного навантаження JWT, `AdminJwtPayload` та `UserJwtPayload`, і об'єднує їх у дискриміноване об'єднання `JwtPayload`. Властивість `type` діє як дискримінатор, дозволяючи вам безпечно отримувати доступ до властивостей на основі типу корисного навантаження.

2. Дженерики для повторно використовуваної логіки автентифікації

Якщо у вас є кілька схем автентифікації з різними структурами корисного навантаження, ви можете використовувати дженерики для створення повторно використовуваної логіки автентифікації.

interface BaseJwtPayload {
  userId: string;
  iat: number;
  exp: number;
}

function verifyToken(token: string): T | null {
  try {
    const decoded = jwt.verify(token, JWT_SECRET) as T;
    return decoded;
  } catch (error) {
    console.error('JWT verification error:', error);
    return null;
  }
}

const adminToken = verifyToken('admin-token');
if (adminToken) {
  console.log('Admin email:', adminToken.email);
}

Цей приклад визначає функцію `verifyToken`, яка приймає дженерик-тип `T`, що розширює `BaseJwtPayload`. Це дозволяє вам перевіряти токени з різними структурами корисного навантаження, гарантуючи при цьому, що всі вони мають принаймні властивості `userId`, `iat` та `exp`.

Особливості глобальних застосунків

При створенні систем автентифікації для глобальних застосунків враховуйте наступне:

• Локалізація: Переконайтеся, що повідомлення про помилки та елементи інтерфейсу користувача локалізовані для різних мов та регіонів.
• Часові пояси: Коректно обробляйте часові пояси при встановленні часу закінчення терміну дії токена та відображенні дат і часу для користувачів.
• Конфіденційність даних: Дотримуйтесь правил конфіденційності даних, таких як GDPR та CCPA. Мінімізуйте кількість персональних даних, що зберігаються в JWT.
• Доступність: Проєктуйте ваші потоки автентифікації так, щоб вони були доступні для користувачів з обмеженими можливостями.
• Культурна чутливість: Будьте уважні до культурних відмінностей при проєктуванні користувацьких інтерфейсів та потоків автентифікації.

Висновок

Використовуючи систему типів TypeScript, ви можете створювати надійні та прості в обслуговуванні системи JWT-автентифікації для глобальних застосунків. Визначення типів корисного навантаження за допомогою інтерфейсів, створення типізованих сервісів JWT, захист кінцевих точок API за допомогою middleware та реалізація RBAC є важливими кроками для забезпечення безпеки та типізації. Враховуючи особливості глобальних застосунків, такі як локалізація, часові пояси, конфіденційність даних, доступність та культурна чутливість, ви можете створити інклюзивний та зручний для користувачів досвід автентифікації для різноманітної міжнародної аудиторії. Пам'ятайте, що завжди слід надавати пріоритет найкращим практикам безпеки при роботі з JWT, включаючи безпечне керування ключами, вибір алгоритму, термін дії токена та його зберігання. Використовуйте потужність TypeScript для створення безпечних, масштабованих та надійних систем автентифікації для ваших глобальних застосунків.